DOpus Plus

home *** CD-ROM | disk | FTP | other *** search

/ DOpus Plus / DOpus Plus.iso / SDK / docs / hooks.doc < prev next >

Wrap

Text File | 1998-10-26 | 23.1 KB | 588 lines

The DOpus Hooks are a series of hook functions which offer you direct access to some of the internals of Directory Opus. Using these functions offers significant speed advantages and is considerably more convenient than using ARexx. To get a pointer to the hooks, you need to initialise a DOpusCallbackInfo structure and send it to the Opus main process. Set the dc_Count field to the number of hooks you want (the best thing is to set it to DOPUS_HOOK_COUNT). DOpusCallbackInfo info; short num; info.dc_Count=DOPUS_HOOK_COUNT; num=IPC_Command(opus_main_ipc,HOOKCMD_GET_CALLBACKS,0,&info,0,REPLY_NO_PORT); The return value from this message will be the number of hooks copied into your structure. If this is 0, you will know this is an older version of Opus that does not support hooks (this is a cheap way to do a version check). More hook functions will be added in the future, and this structure will grow appropriately. You should never attempt to use a hook without checking to see if its pointer is valid. Once you have an initialised structure you can call the hook functions directly (ie no message passing). APTR dc_CreateFileEntry( ULONG lister, struct FileInfoBlock *fib, BPTR lock); This function creates a file entry, ready to be added to a lister. Pass it the lister handle and a filled out FileInfoBlock structure. The 'lock' argument is optional; if not set to NULL it should be a lock on the directory containing the FileInfoBlock (and is used for resolving links). The information in the FileInfoBlock structure is copied and can be disposed of when this function returns. The FileInfoBlock structure does not need to be longword-aligned. void dc_FileSet( ULONG lister, APTR entry, struct TagItem *tags); This command allows you to add or modify entry information. It is mainly used BEFORE an entry has been added to a list but can be used after. Pass an array of tags with the item ID in ti_Tag and the new value in ti_Data. Valid tags for this function are: HFFS_NAME - The name of the entry (char *) HFFS_SIZE - The size of the entry (ULONG) HFFS_PROTECTION - Protection flags (ULONG) HFFS_DATE - Entry date (struct Datestamp *) HFFS_COMMENT - Comment (char *) HFFS_SELECTED - Selected state (BOOL) HFFS_LINK - Indicates a 'link' (BOOL) HFFS_COLOUR - Entry colour (1 = device colour, 2 = assign colour) HFFS_USERDATA - User-defined data (ULONG) HFFS_FILETYPE - Filetype description (char *) HFFS_DISPLAY - Custom display string (char *) HFFS_VERSION - Version Information (VersionInfo *) HFFS_MENU - Custom menus (struct List *) A note about custom menus: To add custom menus to the pop-up menu for an entry, use the HFFS_MENU tag. ti_Data should point to a struct List *, the ln_Name field of the nodes should contain the names of the menu items. Note that the names of menu items are NOT copied (to conserve memory) and so must remain valid while the entry is in use. void dc_SortFileList( ULONG lister, struct List *list, long file_count, long dir_count); This function allows you to add and quicksort a list of entries at once. It is much faster than multiple dc_AddFileEntry() commands. To use it, you should add the return values from your calls to dc_CreateFileEntry() to an initialised exec List structure. Then, pass the list structure along with a count of the number of files and number of directories in the list to this function. Eg, struct List file_list; long file_count=0,dir_count=0; DOpusCallbackInfo info; NewList(&file_list); while (entries_to_add) { entry=info.dc_CreateFileEntry(lister,fib,0); AddTail(&file_list,(struct Node *)entry); if (fib->fib_DirEntryType<0) ++file_count; else ++dir_count; } info.dc_SortFileList(lister,&list,file_count,dir_count); APTR dc_AddFileEntry( ULONG lister, APTR entry, BOOL sort); This function adds a file entry to a lister. Pass it the lister handle and the return value of the dc_CreateFileEntry() command. If sort==TRUE, the entry will be added using the lister's current sort method, otherwise it will just be added to the end of the list. If you have a whole directory to add, dc_SortFileList() is quicker. However, using dc_AddFileEntry() with sort==FALSE and then calling dc_ResortLister() isn't that much slower. void dc_ResortLister( ULONG lister, ListFormat *format); This hook allows you to resort the lister, optionally with a new sort format. If you pass NULL for the format parameter, the list will be resorted using the current settings. Use this hook if you have added multiple files with the dc_AddFileEntry() hook and now wish to sort them (a quicksort will be used). void dc_RefreshLister( ULONG lister, ULONG flags); Allows you to refresh a lister; you should call it after adding entries with the above commands. The HOOKREFRESH_DATE flag indicates that the lister should update its datestamp (to prevent it being automatically re-read). The HOOKREFRESH_FULL flag causes a total refresh of the lister, including the title. void dc_LockFileList( ULONG lister, BOOL exclusive) You should use this to protect the file list from changes by other tasks. Set 'exclusive' to TRUE if you are going to be adding or removing entries from the list; set to FALSE if you are just looking at list entries. void dc_UnlockFileList( ULONG lister) If you have locked the list with dc_LockFileList() you MUST call this function when you have finished. APTR dc_FindFileEntry( ULONG lister, char *name) Searches the file list for a named entry, and returns a handle to it if found. This handle can then be used with dc_FileSet() and dc_FileQuery(), or dc_RemoveFileEntry(). void dc_RemoveFileEntry( ULONG lister, APTR entry) Removed an entry from a list and frees the memory associated with it. The lister display is not updated automatically. BOOL dc_FileQuery( ULONG lister, APTR entry, struct TagItem *tags) Lets you query a file entry. This function uses the same tags as the dc_FileSet() function does. The ti_Data field of each TagItem should point to the appropriate memory area to store the result. That is, HFFS_NAME HFFS_COMMENT HFFS_FILETYPE HFFS_DISPLAY For the string items, ti_Data MUST point to a buffer big enough to receive the string (256 characters is safe in most cases). HFFS_SIZE HFFS_PROTECTION HFFS_SELECTED HFFS_LINK HFFS_USERDATA For these items, ti_Data must point to a ULONG, in which the value will be stored. HFFS_DATE ti_Data must point to a (struct DateStamp), which will be used to store the date. HFFS_VERSION This tag is slightly different. ti_Data must point to a VersionInfo * (ie a 4-byte pointer, NOT an instance of a VersionInfo structure itself). DOpus will allocate a VersionInfo structure and store a pointer to it in the address you provide in ti_Data. When you have finished with the version information, you must call FreeVec() on the memory. void dc_ShowHelp( char *file_name, char *node_name) Calls the internal Opus help system to display help (via AmigaGuide) on the given topic. If file_name is specified, it must be the name of an AmigaGuide help file in the dopus5:Help/ directory. If NULL is given for the file name, the default Opus help file will be used. node_name is the name within the guide of the node to display. *** The following hooks are a new interface to the old module callback system, and take and return similar parameters. The 'handle' parameter in any functions that take it is passed to the Module_Entry() function in your module *** APTR dc_ConvertEntry( APTR entry) Takes an entry as returned by the dc_GetEntry() function and converts it to an entry you can use with the dc_FileSet()/dc_FileQuery()/etc.. functions. You MUST use this as the two entry types are not compatible with each other. Use the return value from this as the entry pointer to pass (the old entry pointer is still valid too). ULONG dc_GetLister( APTR path) Takes a path as returned by the dc_GetSource(), etc functions, and converts it to a lister handle that you can use with the dc_AddFileEntry() and similar functions. APTR dc_GetSource( APTR handle, char *path) Copies the current source path into the supplied buffer (must be at least 512 bytes in size). The return value is a pointer to the path handle; you can use this with other hook functions. This hook is the same as the old EXTCMD_GET_SOURCE callback function. APTR dc_EndSource( APTR handle, long ununsed) Call this hook if you are aborting early and do not wish to process further source paths. Set the 'unused' parameter to 0. This hook is the same as the old EXTCMD_END_SOURCE callback function. APTR dc_NextSource( APTR handle, char *path) Call this hook when you have finished with the first source path and want to move onto the next one. The return value is the new path handle, or NULL if there are no more source paths. This hook is the same as the old EXTCMD_NEXT_SOURCE callback function. void dc_UnlockSource( APTR handle) When your module command is called, any source listers are locked automatically. Call this command when you want to unlock them (they are unlocked automatically when your module returns). This hook is the same as the old EXTCMD_UNLOCK_SOURCE callback function. void dc_GetDest( APTR handle, char *path) Copies the current destination path into the supplied buffer (must be at least 512 bytes in size). The return value is a pointer to the path handle; you can use this with other hook functions. Call this command repeatedly to move through the destination paths. When all the destination paths have been used, this command will return NULL. If you call this command again, it will start again with the first destination path. This hook is the same as the old EXTCMD_GET_DEST callback function. void dc_EndDest( APTR handle, long continue) You must call this command when you have finished with one destination path, prior to calling dc_GetDest(). This hook is the same as the old EXTCMD_END_DEST callback function. void dc_FirstEntry( APTR handle) You must call this hook before you call dc_GetEntry() for the first time. You can call it any time you want to reset the file list to the first entry. APTR dc_GetEntry( APTR handle) This returns a pointer to the next entry in the current source path. Use the dc_ExamineEntry() hook function to get information about the entry. This hook is the same as the old EXTCMD_GET_ENTRY callback function. You must call dc_FirstEntry() before you call this hook for the first time. ULONG dc_ExamineEntry( APTR entry, long type) Returns information about an entry handle retrieved with dc_GetEntry(). 'type' can be either EE_NAME, which returns a pointer to the name, or EE_TYPE, which returns the type of the entry. void dc_EndEntry( APTR handle, APTR entry, BOOL deselect) Call this hook when you have finished working with one entry and want to move on to the next. 'entry' is the pointer that was returned by dc_GetEntry(). Set 'deselect' to TRUE to have the entry deselected in the lister. This hook is the same as the old EXTCMD_NEXT_ENTRY callback function. void dc_ReloadEntry( APTR handle, APTR entry) This function marks the specified entry to be reloaded. When the function finishes, the entry will be reloaded to update any changes that your module might have made to it. This hook is the same as the old EXTCMD_RELOAD_ENTRY callback function. void dc_RemoveEntry( APTR entry) This function marks the specified entry to be removed. When the function finishes, the entry will be removed from the lister it is in. This hook is the same as the old EXTCMD_REMOVE_ENTRY callback function. long dc_EntryCount( APTR handle) Returns the number of selected entries for the function. This hook is the same as the old EXTCMD_ENTRY_COUNT callback function. long dc_AddFile( APTR handle, char *path, struct FileInfoBlock *fib, APTR lister) Allows you to add a file or directory to a lister. The 'path' field points to the full path of the file to add. 'fib' is an initialised FileInfoBlock which is used to create the file entry. The 'lister' pointer is obtained via a call to the dc_GetLister() function. The display is not updated until you call dc_DoChanges(), or your function returns. This hook is the same as the old EXTCMD_ADD_FILE callback function. void dc_DelFile( APTR handle, char *path, char *name, APTR lister) This removes the specified file from any listers it is currently shown in. The file itself is not deleted, only the display of it in the lister. The display is not updated until you call dc_DoChanges(), or your function returns. This hook is the same as the old EXTCMD_DEL_FILE callback function. void dc_LoadFile( APTR handle, char *path, char *name, long flags, BOOL reload) This function is similar to dc_AddFile() except that it takes a filename and path and supplies the FileInfoBlock structure itself. 'path' is the full path of the file and 'name' is the file name. If 'flags' is set to LFF_ICON, the icon of the supplied file will be loaded instead of the file itself. If 'reload' is set to TRUE, an existing file will be reloaded (ie the old entry in the lister will be removed). This hook is the same as the old EXTCMD_LOAD_FILE callback function. void dc_DoChanges( APTR handle) This command causes any changes made to listers by the dc_AddFile(), dc_DelFile() and dc_LoadFile() commands to be displayed. If your function returns without calling this command, the changes are displayed automatically. This hook is the same as the old EXTCMD_DO_CHANGES callback function. BOOL dc_CheckAbort( APTR handle) This hook returns TRUE if your function has been aborted by the user. This could have occurred because the user pressed escape or clicked the close button on a lister, clicked the Abort button in the progress window or quit the program. This hook is the same as the old EXTCMD_CHECK_ABORT callback function. struct Window *dc_GetWindow( APTR path) This function returns a pointer to the Window for the lister specified by the supplied path handle (as returned by dc_GetSource(), etc). This is useful if you want to open a requester over a lister window. This hook is the same as the old EXTCMD_GET_WINDOW callback function. struct MsgPort *dc_GetPort( char *name) This function copies the name of the Opus ARexx port into the supplied buffer (max 40 bytes), and returns a pointer to the message port. This hook is the same as the old EXTCMD_GET_PORT callback function. struct Screen *dc_GetScreen( char *name) This function copies the name of the Opus public screen into the supplied buffer (max 40 bytes), and returns a pointer to the screen. This hook is the same as the old EXTCMD_GET_SCREEN callback function. long dc_ReplaceReq( struct Window *window, struct Screen *screen, IPCData *ipc, struct FileInfoBlock *file1, struct FileInfoBlock *file2, long flags) This function shows a 'file exists - replace?' requester, comparing the two supplied files. Set either the value of 'window' or 'screen' to specify where the requester is to open. 'ipc' is your IPC pointer. 'file1' and 'file2' are the two files. If the REPREQF_NOVERSION flag value is set for the 'flags' parameter, the requester will not display a button to allow version checking. The result of this function is REPLACE_ABORT for abort, REPLACE_LEAVE for skip or REPLACE_REPLACE for replace. If the REPLACEF_ALL flag is set in the result, it indicates an 'All' gagdet (ie Skip All, Replace All). This hook is the same as the old EXTCMD_REPLACE_REQ callback function. DOpusScreenData *dc_GetScreenData(void) Returns a structure with useful information about the Opus screen. This structure is READ_ONLY! You must call dc_FreeScreenData() to free the structure when you have finished with it. This hook is the same as the old EXTCMD_GET_SCREENDATA callback function. void dc_FreeScreenData( DOpusScreenData *data) Frees the result of a dc_GetScreenData() function call. This hook is the same as the old EXTCMD_FREE_SCREENDATA callback function. void dc_OpenProgress( APTR path, char *operation, long total) This opens the lister progress indicator for the specified path handle. 'operation' is the operation string displayed in the title bar, and 'total' is the total number of files to process. This hook is the same as the old EXTCMD_OPEN_PROGRESS callback function. void dc_UpdateProgress( APTR path, char *name, long count) This updates an open progress indicator. 'path' is the path handle that you previously opened a progress indicator for. 'name' is the new filename to display, and 'count' is the new count of files processed. This hook is the same as the old EXTCMD_UPDATE_PROGRESS callback function. void dc_CloseProgress( APTR path) Closes the progress indicator for the specified path. This hook is the same as the old EXTCMD_CLOSE_PROGRESS callback function. long dc_SendCommand( APTR handle, char *command, char **result, ULONG flags) This command sends an ARexx instruction directly to the Opus ARexx port. If you want a result string returned, pass a pointer to a char * in 'result', and set 'flags' to COMMANDF_RESULT. If a string is returned, your supplied pointer will have the address of the string stored in it. You MUST call FreeVec() on this pointer when you have finished with the result. This function returns the RC result of the call. This hook is the same as the old EXTCMD_SEND_COMMAND callback function. void dc_CheckDesktop( char *path) This command is used when your program has just copied one or more files to a directory. You pass it the destination path that you copied the files to, and DOpus compares this path with the location of the Desktop folder. If they are the same, DOpus will then scan the Desktop folder and update the icons on-screen if necessary. This slightly clumsy method has been used because of problems in the system notification routines. short dc_GetDesktop( char *buffer); This command lets you get the path of the DOpus Desktop Folder. The buffer you supply MUST be at least 256 bytes. The current Desktop Folder path will be copied to this buffer. The return value of this hook indicates the user's desktop settings: 0 desktop popup disabled 1 no default action 2 default : create leftout 3 default : move 4 default : copy short dc_Script( char *name, char *data); This command lets you get trigger one of the internal Opus script functions. The script is specified by name (which is not case-sensitive), and the optional data provided is made available to the script function in the {Qa} parameter. short dc_DesktopPopup( ULONG flags) This command causes Opus to display the desktop popup menu. The menu will be displayed at the current mouse position. The value returns is one of the following: 0 cancelled 1 create leftout 2 copy to desktop 3 move to desktop While you can not configure the items in the menu, you can use the flags value to disable the standard items. Set the appropriate bit in the flags value to disable each item in the menu (eg set bit 1 to disable the 'create leftout' option). If you want to have your own items in the popup menu, you will have to implement it yourself. APTR dc_GetPointer( struct GetPointerPkt *); This command lets you retrieve internal information from Opus. You pass it an initialised struct GetPointerPkt, and it returns a pointer to the information you requested. The packet must be initialised with the gpp_Type field set to the information type you desire. The gpp_Ptr and gpp_Flags fields MUST be initialised to 0. Currently, the only defined type is GETPTR_COMMANDS, which returns a list of the Opus internal commands. When this function returns, gpp_Ptr will point to the information you requested. If this function fails, it returns 0 and gpp_Ptr is left unchanged. The gpp_Flags field is not currently used. You MUST call dc_FreePointer when you have finished with the data. In the case of GETPTR_COMMANDS, gpp_Ptr points to a struct List * which contains a list of struct DOpusCommandList entries. APTR dc_FreePointer( struct GetPointerPkt *); When you have finished with the information returned by dc_GetPointer(), you MUST call dc_FreePointer. You must pass dc_FreePointer() the same GetPointerPkt structure that you passed to dc_GetPointer.